home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / dev / gcc / gcc260utilsdoc.lha / gnu / man / man1 / gdbm.1 < prev    next >
Encoding:
Text File  |  1994-07-28  |  15.4 KB  |  595 lines
  1.  
  2.  
  3.  
  4. GDBM(3)                C LIBRARY FUNCTIONS                GDBM(3)
  5.  
  6.  
  7.  
  8. NAME
  9.      GDBM - The GNU database manager.  Includes dbm and ndbm com-
  10.      patability. (Version 1.7.3.)
  11.  
  12. SYNOPSIS
  13.      #include <gdbm.h>
  14.  
  15.      extern gdbm_error
  16.      gdbm_errno
  17.  
  18.      extern char
  19.      *gdbm_version
  20.  
  21.      GDBM_FILE
  22.      gdbm_open (name, block_size, read_write, mode, fatal_func)
  23.      char * name;
  24.      int block_size, read_write, mode;
  25.      void (*fatal_func) ();
  26.  
  27.      void
  28.      gdbm_close (dbf)
  29.      GDBM_FILE dbf;
  30.  
  31.      int
  32.      gdbm_store (dbf, key, content, flag)
  33.      GDBM_FILE dbf;
  34.      datum key, content;
  35.      int flag;
  36.  
  37.      datum
  38.      gdbm_fetch (dbf, key)
  39.      GDBM_FILE dbf;
  40.      datum key;
  41.  
  42.      int
  43.      gdbm_delete (dbf, key)
  44.      GDBM_FILE dbf;
  45.      datum key;
  46.  
  47.      datum
  48.      gdbm_firstkey (dbf)
  49.      GDBM_FILE dbf;
  50.  
  51.      datum
  52.      gdbm_nextkey (dbf, key)
  53.      GDBM_FILE dbf;
  54.      datum key;
  55.  
  56.      int
  57.      gdbm_reorganize (dbf)
  58.      GDBM_FILE dbf;
  59.  
  60.  
  61.  
  62.  
  63. Sun Release 4.1       Last change: 5/19/94                      1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GDBM(3)                C LIBRARY FUNCTIONS                GDBM(3)
  71.  
  72.  
  73.  
  74.      void
  75.      gdbm_sync (dbf)
  76.      GDBM_FILE dbf;
  77.  
  78.      int
  79.      gdbm_exists (dbf, key)
  80.      GDBM_FILE dbf;
  81.      datum key;
  82.  
  83.      char *
  84.      gdbm_strerror (errno)
  85.      gdbm_error errno;
  86.  
  87.      int
  88.      gdbm_setopt (dbf, option, value, size)
  89.      GDBM_FILE dbf;
  90.      int option;
  91.      int *value;
  92.      int size;
  93.  
  94.      DBM Compatability routines:
  95.  
  96.      #include <dbm.h>
  97.  
  98.      int
  99.      dbminit (name)
  100.      char *name;
  101.  
  102.      int
  103.      store (key, content)
  104.      datum key, content;
  105.  
  106.      datum
  107.      fetch (key)
  108.      datum key;
  109.  
  110.      int
  111.      delete (key)
  112.      datum key;
  113.  
  114.      datum
  115.      firstkey ()
  116.  
  117.      datum
  118.      nextkey (key)
  119.      datum key;
  120.  
  121.      int
  122.      dbmclose ()
  123.  
  124.      NDBM Compatability routines:
  125.  
  126.  
  127.  
  128.  
  129. Sun Release 4.1       Last change: 5/19/94                      2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GDBM(3)                C LIBRARY FUNCTIONS                GDBM(3)
  137.  
  138.  
  139.  
  140.      #include <ndbm.h>
  141.  
  142.      DBM
  143.      *dbm_open (name, flags, mode)
  144.      char *name;
  145.      int flags, mode;
  146.  
  147.      void
  148.      dbm_close (file)
  149.      DBM *file;
  150.  
  151.      datum
  152.      dbm_fetch (file, key)
  153.      DBM *file;
  154.      datum key;
  155.  
  156.      int
  157.      dbm_store (file, key, content, flags)
  158.      DBM *file;
  159.      datum key, content;
  160.      int flags;
  161.  
  162.      int
  163.      dbm_delete (file, key)
  164.      DBM *file;
  165.      datum key;
  166.  
  167.      datum
  168.      dbm_firstkey (file)
  169.      DBM *file;
  170.  
  171.      datum
  172.      dbm_nextkey (file)
  173.      DBM *file;
  174.  
  175.      int
  176.      dbm_error (file)
  177.      DBM *file;
  178.  
  179.      int
  180.      dbm_clearerr (file)
  181.      DBM *file;
  182.  
  183.      int
  184.      dbm_pagfno (file)
  185.      DBM *file;
  186.  
  187.      int
  188.      dbm_dirfno (file)
  189.      DBM *file;
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sun Release 4.1       Last change: 5/19/94                      3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. GDBM(3)                C LIBRARY FUNCTIONS                GDBM(3)
  203.  
  204.  
  205.  
  206.      int
  207.      dbm_rdonly (file)
  208.      DBM *file;
  209.  
  210.  
  211.  
  212. DESCRIPTION
  213.      GNU dbm is a library of routines  that  manages  data  files
  214.      that contain key/data pairs.  The access provided is that of
  215.      storing, retrieval, and deletion by  key  and  a  non-sorted
  216.      traversal of all keys.  A process is allowed to use multiple
  217.      data files at the same time.
  218.  
  219.      A process that opens a gdbm file is designated as a "reader"
  220.      or  a  "writer".   Only  one writer may open a gdbm file and
  221.      many readers may open the file.  Readers and writers can not
  222.      open the gdbm file at the same time. The procedure for open-
  223.      ing a gdbm file is:
  224.  
  225.        GDBM_FILE dbf;
  226.  
  227.        dbf = gdbm_open  (  name,  block_size,  read_write,  mode,
  228.      fatal_func )
  229.  
  230.      _N_a_m_e is the name of the file (the complete name,  gdbm  does
  231.      not  append any characters to this name).  _B_l_o_c_k__s_i_z_e is the
  232.      size of a single transfer from disk to memory. This  parame-
  233.      ter  is  ignored unless the file is a new file.  The minimum
  234.      size is 512.  If it is less than 512, dbm will use the  stat
  235.      block  size for the file system.  _R_e_a_d__w_r_i_t_e can have one of
  236.      the following values:
  237.      GDBM_READER reader
  238.      GDBM_WRITER writer
  239.      GDBM_WRCREAT writer - if database does not exist create  new
  240.      one
  241.      GDBM_NEWDB writer - create new database  regardless  if  one
  242.      exists
  243.      For the last three (writers of the  database)  there  is  an
  244.      extra  value that that can be added to _r_e_a_d__w_r_i_t_e by bitwise
  245.      or, GDBM_FAST. This requests that gdbm  write  the  database
  246.      with  no  disk  file  syncronization.   This  allows  faster
  247.      writes, but may produce  an  inconsistant  database  in  the
  248.      event of abnormal termination of the writer.
  249.      _M_o_d_e is the file mode (see chmod(2) and open(2)) if the file
  250.      is  created.  (*_F_a_t_a_l__f_u_n_c) () is a function for dbm to call
  251.      if it detects a fatal error.  The  only  parameter  of  this
  252.      function  is  a string.  If the value of 0 is provided, gdbm
  253.      will use a default function.
  254.  
  255.      The return value _d_b_f is the pointer needed by all other rou-
  256.      tines  to  access that gdbm file.  If the return is the NULL
  257.      pointer, gdbm_open was not successful.  The  errors  can  be
  258.  
  259.  
  260.  
  261. Sun Release 4.1       Last change: 5/19/94                      4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. GDBM(3)                C LIBRARY FUNCTIONS                GDBM(3)
  269.  
  270.  
  271.  
  272.      found  in _g_d_b_m__e_r_r_n_o for gdbm errors and in _e_r_r_n_o for system
  273.      errors.  (For error codes, see gdbmerrno.h.)
  274.  
  275.      In all of the following calls, the parameter _d_b_f  refers  to
  276.      the pointer returned from gdbm_open.
  277.  
  278.      It is important that every file opened is also closed.  This
  279.      is  needed  to  update  the reader/writer count on the file.
  280.      This is done by:
  281.  
  282.        gdbm_close (dbf);
  283.  
  284.  
  285.      The database is used  by  3  primary  routines.   The  first
  286.      stores data in the database.
  287.  
  288.        ret = gdbm_store ( dbf, key, content, flag )
  289.  
  290.      _D_b_f is the pointer returned by gdbm_open.  _K_e_y  is  the  key
  291.      data.   _C_o_n_t_e_n_t  is  the data to be associated with the _k_e_y.
  292.      _F_l_a_g can have one of the following values:
  293.      GDBM_INSERT insert only, generate an error if key exists
  294.      GDBM_REPLACE replace contents if key exists.
  295.  
  296.      If a reader calls gdbm_store, the return value will be   -1.
  297.      If  called  with GDBM_INSERT and _k_e_y is in the database, the
  298.      return value will be 1.  Otherwise, the return value is 0.
  299.  
  300.      _N_O_T_I_C_E: _I_f _y_o_u _s_t_o_r_e _d_a_t_a _f_o_r _a _k_e_y _t_h_a_t _i_s _a_l_r_e_a_d_y  _i_n  _t_h_e
  301.      _d_a_t_a  _b_a_s_e,  _g_d_b_m _r_e_p_l_a_c_e_s _t_h_e _o_l_d _d_a_t_a _w_i_t_h _t_h_e _n_e_w _d_a_t_a _i_f
  302.      _c_a_l_l_e_d _w_i_t_h _G_D_B_M__R_E_P_L_A_C_E.  _Y_o_u _d_o _n_o_t _g_e_t _t_w_o _d_a_t_a _i_t_e_m_s _f_o_r
  303.      _t_h_e _s_a_m_e _k_e_y _a_n_d _y_o_u _d_o _n_o_t _g_e_t _a_n _e_r_r_o_r _f_r_o_m _g_d_b_m__s_t_o_r_e.
  304.  
  305.      _N_O_T_I_C_E: _T_h_e _s_i_z_e _i_n _g_d_b_m _i_s _n_o_t _r_e_s_t_r_i_c_t_e_d _l_i_k_e _d_b_m _o_r _n_d_b_m.
  306.      _Y_o_u_r _d_a_t_a _c_a_n _b_e _a_s _l_a_r_g_e _a_s _y_o_u _w_a_n_t.
  307.  
  308.  
  309.      To search for some data:
  310.  
  311.        content = gdbm_fetch ( dbf, key )
  312.  
  313.      _D_b_f is the pointer returned by gdbm_open.  _K_e_y  is  the  key
  314.      data.
  315.  
  316.  
  317.      If the _d_p_t_r element of the return value is NULL, no data was
  318.      found.  Otherwise the return value is a pointer to the found
  319.      data.  The storage space for the _d_p_t_r element  is  allocated
  320.      using  malloc(3C).   Gdbm  _d_o_e_s  _n_o_t _a_u_t_o_m_a_t_i_c_a_l_l_y _f_r_e_e _t_h_i_s
  321.      _d_a_t_a.  _I_t _i_s _t_h_e _p_r_o_g_r_a_m_m_e_r'_s _r_e_s_p_o_n_s_i_b_i_l_i_t_y  _t_o  _f_r_e_e  _t_h_i_s
  322.      _s_t_o_r_a_g_e _w_h_e_n _i_t _i_s _n_o _l_o_n_g_e_r _n_e_e_d_e_d.
  323.  
  324.  
  325.  
  326.  
  327. Sun Release 4.1       Last change: 5/19/94                      5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. GDBM(3)                C LIBRARY FUNCTIONS                GDBM(3)
  335.  
  336.  
  337.  
  338.      To search for some data, without retrieving it:
  339.  
  340.        ret = gdbm_exists ( dbf, key )
  341.  
  342.      _D_b_f is the pointer returned by gdbm_open.  _K_e_y  is  the  key
  343.      data to search for.
  344.  
  345.      If the _k_e_y is found within the database,  the  return  value
  346.      _r_e_t  will be true.  If nothing appropiate is found, _r_e_t will
  347.      be false.  This routine is useful for checking for the exis-
  348.      tance  of a record, without performing the memory allocation
  349.      done by gdbm_fetch.
  350.  
  351.  
  352.      To remove some data from the database:
  353.  
  354.        ret = gdbm_delete ( dbf, key )
  355.  
  356.      _D_b_f is the pointer returned by gdbm_open.  _K_e_y  is  the  key
  357.      data.
  358.  
  359.      The return value is -1 if the item is  not  present  or  the
  360.      requester is a reader.  The return value is 0 if there was a
  361.      successful delete.
  362.  
  363.  
  364.      The next two routines allow for accessing all items  in  the
  365.      database.   This  access  is  not  key sequential, but it is
  366.      guaranteed to visit every key in the  database  once.   (The
  367.      order has to do with the hash values.)
  368.  
  369.        key = gdbm_firstkey ( dbf )
  370.  
  371.        nextkey = gdbm_nextkey ( dbf, key )
  372.  
  373.      _D_b_f is the pointer returned by gdbm_open.  _K_e_y  is  the  key
  374.      data.
  375.  
  376.      The return values are both of type datum.  If the _d_p_t_r  ele-
  377.      ment  of  the return value is NULL, there is no first key or
  378.      next key.  Again notice that _d_p_t_r points to  data  allocated
  379.      by malloc(3C) and gdbm will not free it for you.
  380.  
  381.      These functions were  intended  to  visit  the  database  in
  382.      read-only algorithms, for instance, to validate the database
  383.      or similar operations.
  384.  
  385.      File `visiting' is based on  a  `hash  table'.   _g_d_b_m__d_e_l_e_t_e
  386.      re-arranges  the hash table to make sure that any collisions
  387.      in the table do not leave some item `un-findable'.  The ori-
  388.      ginal key order is NOT guaranteed to remain unchanged in ALL
  389.      instances.  It is possible that some key will not be visited
  390.  
  391.  
  392.  
  393. Sun Release 4.1       Last change: 5/19/94                      6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. GDBM(3)                C LIBRARY FUNCTIONS                GDBM(3)
  401.  
  402.  
  403.  
  404.      if a loop like the following is executed:
  405.  
  406.         key = gdbm_firstkey ( dbf );
  407.         while ( key.dptr ) {
  408.            nextkey = gdbm_nextkey ( dbf, key );
  409.            if ( some condition ) {
  410.               gdbm_delete ( dbf, key );
  411.               free ( key.dptr );
  412.            }
  413.            key = nextkey;
  414.         }
  415.  
  416.  
  417.      The following routine should be used very infrequently.
  418.  
  419.        ret = gdbm_reorganize ( dbf )
  420.  
  421.      If you have had a lot of deletions and would like to  shrink
  422.      the  space used by the gdbm file, this routine will reorgan-
  423.      ize the database.  Gdbm will not shorten  the  length  of  a
  424.      gdbm  file  except  by  using this reorganization.  (Deleted
  425.      file space will be reused.)
  426.  
  427.  
  428.      If you use the GDBM_FAST value in your gdbm_open  call,  the
  429.      following routine can be used to guarantee that the database
  430.      is physically written to the disk file.
  431.  
  432.        gdbm_sync ( dbf )
  433.  
  434.      It will not return until the disk file state is  syncronized
  435.      with the in-memory state of the database.
  436.  
  437.  
  438.      To convert a gdbm error code into  English  text,  use  this
  439.      routine:
  440.  
  441.        ret = gdbm_strerror ( errno )
  442.  
  443.      Where errno is of type gdbm_error, usually the global  vari-
  444.      able gdbm_errno.  The appropiate phrase is returned.
  445.  
  446.  
  447.      Gdbm now supports the ability to set certain options  on  an
  448.      already open database.
  449.  
  450.        ret = gdbm_setopt ( dbf, option, value, size )
  451.  
  452.      Where dbf is the  return  value  from  a  previous  call  to
  453.      gdbm_open,  and  option  specifies which option to set.  The
  454.      valid options are currently:
  455.  
  456.  
  457.  
  458.  
  459. Sun Release 4.1       Last change: 5/19/94                      7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. GDBM(3)                C LIBRARY FUNCTIONS                GDBM(3)
  467.  
  468.  
  469.  
  470.        GDBM_CACHESIZE - Set the size of the internal bucket
  471.        cache. This option may only be set once on each GDBM_FILE
  472.        descriptor, and is set automatically to 100 upon the first
  473.        access to the database.
  474.  
  475.        GDBM_FASTMODE - Set fast mode to either on or off.  This
  476.        allows fast mode to be toggled on an already open and
  477.        active database. value (see below) should be set to either
  478.        TRUE or FALSE.
  479.  
  480.      value is the value to set option to, specified as an integer
  481.      pointer.   size is the size of the data pointed to by value.
  482.      The return value will be -1 upon failure, or 0 upon success.
  483.      The global variable gdbm_errno will be set upon failure.
  484.  
  485.      For instance, to set a database to use a cache of 10,  after
  486.      opening  it with gdbm_open, but prior to accessing it in any
  487.      way, the following code could be used:
  488.  
  489.        int value = 10;
  490.  
  491.        ret   =   gdbm_setopt(   dbf,   GDBM_CACHESIZE,    &value,
  492.      sizeof(int));
  493.  
  494.  
  495.      The following two external variables may be useful:
  496.  
  497.      gdbm_errno is the variable that  contains  more  information
  498.      about gdbm errors.  (gdbm.h has the definitions of the error
  499.      values and defines gdbm_errno as an external variable.)
  500.      gdbm_version is the string containing the  version  informa-
  501.      tion.
  502.  
  503.  
  504.      There are a few more things of interest.  First, gdbm  files
  505.      are  not  "sparse".   You  can copy them with the UNIX cp(1)
  506.      command and they will not expand  in  the  copying  process.
  507.      Also,  there  is  a compatibility mode for use with programs
  508.      that already use UNIX dbm.  In this compatibility  mode,  no
  509.      gdbm  file  pointer  is required by the programmer, and only
  510.      one file may be opened at a time.  All users in  compatibil-
  511.      ity  mode  are assumed to be writers.  If the gdbm file is a
  512.      read only, it will fail as a writer, but will  also  try  to
  513.      open  it as a reader.  All returned pointers in datum struc-
  514.      tures point to data that gdbm WILL  free.   They  should  be
  515.      treated as static pointers (as standard UNIX dbm does).
  516.  
  517.  
  518.  
  519. LINKING
  520.      This library is accessed by specifying -_l_g_d_b_m  as  the  last
  521.      parameter to the compile line, e.g.:
  522.  
  523.  
  524.  
  525. Sun Release 4.1       Last change: 5/19/94                      8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. GDBM(3)                C LIBRARY FUNCTIONS                GDBM(3)
  533.  
  534.  
  535.  
  536.           gcc -o prog prog.c -lgdbm
  537.  
  538.  
  539.  
  540. BUGS
  541. SEE ALSO
  542.      dbm, ndbm
  543.  
  544.  
  545. AUTHOR
  546.      by Philip A. Nelson.   Copyright  (C)  1990   Free  Software
  547.      Foundation, Inc.
  548.  
  549.      GDBM is free software; you can redistribute it and/or modify
  550.      it under the terms of the GNU General Public License as pub-
  551.      lished by the Free Software Foundation; either version 1, or
  552.      (at your option) any later version.
  553.  
  554.      GDBM is distributed in the hope that it will be useful,  but
  555.      WITHOUT  ANY  WARRANTY; without even the implied warranty of
  556.      MERCHANTABILITY or FITNESS FOR A  PARTICULAR  PURPOSE.   See
  557.      the GNU General Public License for more details.
  558.  
  559.      You should have received a copy of the  GNU  General  Public
  560.      License  along  with  GDBM;  see  the file COPYING.  If not,
  561.      write to the Free Software Foundation, 675  Mass  Ave,  Cam-
  562.      bridge, MA 02139, USA.
  563.  
  564.      You may contact the author by:
  565.         e-mail:  phil@wwu.edu
  566.        us-mail:  Philip A. Nelson
  567.      Computer Science Department
  568.      Western Washington University
  569.      Bellingham, WA 98226
  570.  
  571.      You may contact the current maintainer by:
  572.         e-mail:  downsj@CSOS.ORST.EDU
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591. Sun Release 4.1       Last change: 5/19/94                      9
  592.  
  593.  
  594.  
  595.